# Rsbuild instance

This section describes all the properties and methods on the Rsbuild instance object.

## rsbuild.context

`rsbuild.context` is a read-only object that provides some context information, which can be accessed in two ways:

1. Access through the `context` property of the Rsbuild instance:

```ts
import { createRsbuild } from '@rsbuild/core';

const rsbuild = createRsbuild({
  // ...
});

console.log(rsbuild.context);
```

2. Access through the [api.context](/plugins/dev/core#apicontext) of the Rsbuild plugin:

```ts
export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    console.log(api.context);
  },
};
```

### context.version

The version of `@rsbuild/core` currently in use.

- **Type:**

```ts
type Version = string;
```

### context.rootPath

The root path of current build, corresponding to the `cwd` option of [createRsbuild](/api/javascript-api/core#creatersbuild) method.

- **Type:**

```ts
type RootPath = string;
```

### context.distPath

The absolute path of the output directory, corresponding to the [output.distPath.root](/config/output/dist-path) config in `RsbuildConfig`.

When there are multiple environments, Rsbuild will try to get the parent distPath of all environments as `context.distPath`.

If you want to get the absolute path to the output directory of a specified environment, it is recommended to use [environment.distPath](/api/javascript-api/environment-api#distpath).

- **Type:**

```ts
type DistPath = string;
```

### context.cachePath

The absolute path of the build cache files.

- **Type:**

```ts
type CachePath = string;
```

### context.callerName

The name of the framework or tool that is currently invoking Rsbuild, same as the [callerName](/api/javascript-api/core#specify-caller-name) option in the [createRsbuild](/api/javascript-api/core#creatersbuild) method.

- **Type:** `string`
- **Default:** `'rsbuild'`
- **Example:**

```ts title="myPlugin.ts"
export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    const { callerName } = api.context;

    if (callerName === 'rslib') {
      // ...
    } else if (callerName === 'rsbuild') {
      // ...
    }
  },
};
```

Here are some tools based on Rsbuild that have already set the `callerName` value:

| Name                                                | callerName  |
| --------------------------------------------------- | ----------- |
| [Rslib](https://github.com/web-infra-dev/rslib)     | `'rslib'`   |
| [Rspress](https://github.com/web-infra-dev/rspress) | `'rspress'` |
| [Rspeedy](https://lynxjs.org/rspeedy)               | `'rspeedy'` |

### context.devServer

Dev server information when running in dev mode. Available after the dev server has been created.

- **Type:**

```ts
type DevServer = {
  hostname: string;
  port: number;
  https: boolean;
};
```

- **Example:**

```ts
import { createRsbuild } from '@rsbuild/core';

async function main() {
  const rsbuild = createRsbuild({
    // ...
  });
  await rsbuild.startDevServer();

  console.log(rsbuild.context.devServer); // { hostname: 'localhost', port: 3000, https: false }
}
```

### context.action

The current action type.

- **Type:**

```ts
type Action = 'dev' | 'build' | 'preview' | undefined;
```

`context.action` is set when running CLI commands or calling Rsbuild instance methods:

- `dev`: will be set when running [rsbuild dev](/guide/basic/cli#rsbuild-dev) or [rsbuild.startDevServer()](/api/javascript-api/instance#rsbuildstartdevserver)
- `build`: will be set when running [rsbuild build](/guide/basic/cli#rsbuild-build) or [rsbuild.build()](/api/javascript-api/instance#rsbuildbuild)
- `preview`: will be set when running [rsbuild preview](/guide/basic/cli#rsbuild-preview) or [rsbuild.preview()](/api/javascript-api/instance#rsbuildpreview)

For example:

```ts
if (rsbuild.context.action === 'dev') {
  // do something
}
```

### context.bundlerType

The bundler type of current build.

- **Type:**

```ts
type bundlerType = 'rspack' | 'webpack';
```

> Rsbuild internally supports switching to webpack for comparative testing, so this field is provided for differentiation. Usually, you do not need to use this field.

## rsbuild.build

Perform a production mode build. This method will generate optimized production bundles and emit them to the output directory.

- **Type:**

```ts
type BuildOptions = {
  /**
   * Whether to watch for file changes and rebuild.
   * @default false
   */
  watch?: boolean;
  /**
   * Using a custom Rspack Compiler object.
   */
  compiler?: Compiler | MultiCompiler;
};

function Build(options?: BuildOptions): Promise<{
  /**
   * Rspack's [stats](https://rspack.rs/api/javascript-api/stats) object.
   */
  stats?: Rspack.Stats | Rspack.MultiStats;
  /**
   * Close the build and call the `onCloseBuild` hook.
   * In watch mode, this method will stop watching.
   */
  close: () => Promise<void>;
}>;
```

- **Example:**

```ts
import { logger } from '@rsbuild/core';

// Example 1: run build
await rsbuild.build();

// Example 2: build and handle the error
try {
  await rsbuild.build();
} catch (err) {
  logger.error('Failed to build.');
  logger.error(err);
  process.exit(1);
}

// Example 3: build and get all assets
const { stats } = await rsbuild.build();

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}
```

### Monitor file changes

To watch file changes and re-build, set the `watch` option to `true`.

```ts
await rsbuild.build({
  watch: true,
});
```

### Close build

`rsbuild.build()` returns a `close()` method, which can be used to stop the build.

In watch mode, calling the `close()` method will stop watching:

```ts
const buildResult = await rsbuild.build({
  watch: true,
});
await buildResult.close();
```

In non-watch mode, you should also call the `close()` method to end the build, which will trigger the [onCloseBuild](/plugins/dev/hooks#onclosebuild) hook to perform cleanup operations.

```ts
const buildResult = await rsbuild.build();
await buildResult.close();
```

### Stats object

In non-watch mode, the `rsbuild.build()` returns an Rspack [stats](https://rspack.rs/api/javascript-api/stats) object.

For example, use the `stats.toJson()` method to get all assets information:

```ts
const result = await rsbuild.build();
const { stats } = result;

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}
```

### Custom compiler

In some cases, you may want to use a custom compiler:

```ts
import { rspack } from '@rsbuild/core';

const compiler = rspack({
  // ...
});
await rsbuild.build({
  compiler,
});
```

## rsbuild.startDevServer

Start the local dev server. This method will:

1. Start a development server that serves your application.
2. Watch for file changes and trigger recompilation.

- **Type:**

```ts
type StartDevServerOptions = {
  /**
   * Using a custom Rspack Compiler object.
   */
  compiler?: Compiler | MultiCompiler;
  /**
   * Whether to get port silently and not print any logs.
   * @default false
   */
  getPortSilently?: boolean;
};

type StartServerResult = {
  /**
   * The URLs that server is listening on.
   */
  urls: string[];
  /**
   * The actual port used by the server.
   */
  port: number;
  server: {
    /**
     * Close the server.
     * In development mode, this will call the `onCloseDevServer` hook.
     */
    close: () => Promise<void>;
  };
};

function StartDevServer(
  options?: StartDevServerOptions,
): Promise<StartServerResult>;
```

- **Example:**

Start dev server:

```ts
import { logger } from '@rsbuild/core';

// Start dev server
await rsbuild.startDevServer();

// Start dev server and handle the error
try {
  await rsbuild.startDevServer();
} catch (err) {
  logger.error('Failed to start dev server.');
  logger.error(err);
  process.exit(1);
}
```

After successfully starting dev server, you can see the following logs:

```
  ➜ Local:    http://localhost:3000
  ➜ Network:  http://192.168.0.1:3000
```

`startDevServer` returns the following parameters:

- `urls`: URLs to access dev server.
- `port`: The actual listening port number.
- `server`: Server instance object.

```ts
const { urls, port } = await rsbuild.startDevServer();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000
```

### Close server

Calling the `close()` method to close the dev server, trigger the [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) hook and perform necessary cleanup operations.

```ts
const { server } = await rsbuild.startDevServer();
await server.close();
```

### Get port silently

In some cases, the default startup port number is already occupied. In this situation, Rsbuild will automatically increment the port number until it finds an available one. This process will output a prompt log. If you do not want this log, you can set `getPortSilently` to `true`.

```ts
await rsbuild.startDevServer({
  getPortSilently: true,
});
```

### Custom compiler

In some cases, you may want to use a custom compiler:

```ts
import { rspack } from '@rsbuild/core';

const compiler = rspack({
  // ...
});
await rsbuild.startDevServer({
  compiler,
});
```

## rsbuild.createDevServer

Rsbuild includes a built-in dev server designed to improve the development experience. When you run the `rsbuild dev` command, the server starts automatically and provides features such as page preview, routing, and hot module reloading.

- To integrate the Rsbuild dev server into a custom server, you can use the `createDevServer` method to create a dev server instance. Please refer to [Dev server API](/api/javascript-api/dev-server-api) for all available APIs.
- To use Rsbuild dev server to start the project directly, you can use the [rsbuild.startDevServer](#rsbuildstartdevserver) method directly. `rsbuild.startDevServer` is actually syntactic sugar for the following code:

```ts
const server = await rsbuild.createDevServer();
await server.listen();
```

## rsbuild.preview

Start a server to preview the production build locally. This method should be executed after [rsbuild.build](#rsbuildbuild).

- **Type:**

```ts
type PreviewOptions = {
  /**
   * Whether to get port silently
   * @default false
   */
  getPortSilently?: boolean;
  /**
   * Whether to check if the dist directory exists and is not empty.
   * @default true
   */
  checkDistDir?: boolean;
};

type StartServerResult = {
  /**
   * The URLs that server is listening on.
   */
  urls: string[];
  /**
   * The actual port used by the server.
   */
  port: number;
  server: {
    /**
     * Close the server.
     */
    close: () => Promise<void>;
  };
};

function preview(options?: PreviewOptions): Promise<StartServerResult>;
```

- **Example:**

Start the server:

```ts
import { logger } from '@rsbuild/core';

// Start preview server
await rsbuild.preview();

// Start preview server and handle the error
try {
  await rsbuild.preview();
} catch (err) {
  logger.error('Failed to start preview server.');
  logger.error(err);
  process.exit(1);
}
```

`preview` returns the following parameters:

- `urls`: URLs to access server.
- `port`: The actual listening port number.
- `server`: Server instance object.

```ts
const { urls, port } = await rsbuild.preview();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000
```

### Close server

Calling the `close()` method will close the preview server.

```ts
const { server } = await rsbuild.preview();
await server.close();
```

## rsbuild.createCompiler

Create an Rspack [Compiler](https://rspack.rs/api/javascript-api/compiler) instance. If there are multiple [environments](/config/environments) for this build, the return value is [MultiCompiler](https://rspack.rs/api/javascript-api/compiler#multicompiler).

- **Type:**

```ts
function CreateCompiler(): Promise<Compiler | MultiCompiler>;
```

- **Example:**

```ts
const compiler = await rsbuild.createCompiler();
```

> You do not need to use this API unless you need to custom the dev server or other advanced scenarios.

## rsbuild.addPlugins

Register one or more Rsbuild plugins, which can be called multiple times.

This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.

- **Type:**

```ts
type AddPluginsOptions = { before?: string; environment?: string };

function AddPlugins(
  plugins: Array<RsbuildPlugin | Falsy>,
  options?: AddPluginsOptions,
): void;
```

- **Example:**

```ts
rsbuild.addPlugins([pluginFoo(), pluginBar()]);

// Insert before the bar plugin
rsbuild.addPlugins([pluginFoo()], { before: 'bar' });

// Add plugin for node environment
rsbuild.addPlugins([pluginFoo()], { environment: 'node' });
```

## rsbuild.getPlugins

Get all the Rsbuild plugins registered in the current Rsbuild instance.

- **Type:**

```ts
function GetPlugins(options?: {
  /**
   * Get the plugins in the specified environment.
   * If environment is not specified, get the global plugins.
   */
  environment: string;
}): RsbuildPlugin[];
```

- **Example:**

```ts
// get all plugins
console.log(rsbuild.getPlugins());

// get plugins in `web` environment
console.log(rsbuild.getPlugins({ environment: 'web' }));
```

## rsbuild.removePlugins

Removes one or more Rsbuild plugins, which can be called multiple times.

This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.

- **Type:**

```ts
function RemovePlugins(pluginNames: string[]): void;
```

- **Example:**

```ts
// add plugin
const pluginFoo = pluginFoo();
rsbuild.addPlugins(pluginFoo);

// remove plugin
rsbuild.removePlugins([pluginFoo.name]);
```

## rsbuild.isPluginExists

import IsPluginExists from '@en/shared/isPluginExists.mdx';

<IsPluginExists />

- **Example:**

```ts
rsbuild.addPlugins([pluginFoo()]);

rsbuild.isPluginExists(pluginFoo().name); // true
```

## rsbuild.initConfigs

Initialize and return the internal Rspack configurations used by Rsbuild. This method processes all plugins and configurations to generate the final Rspack configs.

> Note: You typically don't need to call this method directly since it's automatically invoked by methods like [rsbuild.build](#rsbuildbuild) and [rsbuild.startDevServer](#rsbuildstartdevserver).

- **Type:**

```ts
function InitConfigs(): Promise<{
  rspackConfigs: Rspack.Configuration[];
}>;
```

- **Example:**

```ts
const rspackConfigs = await rsbuild.initConfigs();

console.log(rspackConfigs);
```

## rsbuild.inspectConfig

Inspect and debug Rsbuild's internal configurations. It provides access to:

- The resolved Rsbuild configuration
- The environment-specific Rsbuild configurations
- The generated Rspack configurations

The method serializes these configurations to strings and optionally writes them to disk for inspection.

- **Type:**

```ts
type InspectConfigOptions = {
  /**
   * Inspect the config in the specified mode.
   * Available options: 'development' or 'production'.
   * @default 'development'
   */
  mode?: RsbuildMode;
  /**
   * Enables verbose mode to display the complete function
   * content in the configuration.
   * @default false
   */
  verbose?: boolean;
  /**
   * Specify the output path for inspection results.
   * @default 'output.distPath.root'
   */
  outputPath?: string;
  /**
   * Whether to write the inspection results to disk.
   * @default false
   */
  writeToDisk?: boolean;
};

async function InspectConfig(options?: InspectConfigOptions): Promise<{
  rsbuildConfig: string;
  bundlerConfigs: string[];
  environmentConfigs: string[];
  origin: {
    rsbuildConfig: RsbuildConfig;
    environmentConfigs: Record<string, EnvironmentConfig>;
    bundlerConfigs: BundlerConfigs[];
  };
}>;
```

:::tip
To view the Rsbuild and Rspack configurations during the build process, use [debug mode](/guide/debug/debug-mode), or obtain them through hooks such as [onBeforeBuild](#rsbuildonbeforebuild), [onBeforeCreateCompile](#rsbuildonbeforecreatecompiler).
:::

### Example

Get the content of configs in string format:

```ts
const { rsbuildConfig, bundlerConfigs } = await rsbuild.inspectConfig();

console.log(rsbuildConfig, bundlerConfigs);
```

Write the config content to disk:

```ts
await rsbuild.inspectConfig({
  writeToDisk: true,
});
```

### Output path

You can set the output path using `outputPath`. The default value is [output.distPath.root](/config/output/dist-path).

If `outputPath` is a relative path, it will be concatenated relative to the value of `output.distPath.root`. You can also set `outputPath` to an absolute path, in which case the files will be written directly to that path. For example:

```ts
import path from 'node:path';

await rsbuild.inspectConfig({
  writeToDisk: true,
  outputPath: path.join(__dirname, 'custom-dir'),
});
```

## rsbuild.onBeforeCreateCompiler

> Provides the same functionality as the [onBeforeCreateCompiler](/plugins/dev/hooks#onbeforecreatecompiler) plugin hook.

import OnBeforeCreateCompiler from '@en/shared/onBeforeCreateCompiler.mdx';

<OnBeforeCreateCompiler />

- **Example:**

```ts
rsbuild.onBeforeCreateCompiler(({ bundlerConfigs }) => {
  console.log('the Rspack config is ', bundlerConfigs);
});
```

## rsbuild.onAfterCreateCompiler

> Provides the same functionality as the [onAfterCreateCompiler](/plugins/dev/hooks#onaftercreatecompiler) plugin hook.

import OnAfterCreateCompiler from '@en/shared/onAfterCreateCompiler.mdx';

<OnAfterCreateCompiler />

- **Example:**

```ts
rsbuild.onAfterCreateCompiler(({ compiler }) => {
  console.log('the compiler is ', compiler);
});
```

## rsbuild.onBeforeBuild

> Provides the same functionality as the [onBeforeBuild](/plugins/dev/hooks#onbeforebuild) plugin hook.

import OnBeforeBuild from '@en/shared/onBeforeBuild.mdx';

<OnBeforeBuild />

- **Example:**

```ts
rsbuild.onBeforeBuild(({ bundlerConfigs }) => {
  console.log('the Rspack config is ', bundlerConfigs);
});
```

## rsbuild.onAfterBuild

> Provides the same functionality as the [onAfterBuild](/plugins/dev/hooks#onafterbuild) plugin hook.

import OnAfterBuild from '@en/shared/onAfterBuild.mdx';

<OnAfterBuild />

- **Example:**

```ts
rsbuild.onAfterBuild(({ stats }) => {
  console.log(stats?.toJson());
});
```

## rsbuild.onCloseBuild

> Provides the same functionality as the [onCloseBuild](/plugins/dev/hooks#onclosebuild) plugin hook.

import OnCloseBuild from '@en/shared/onCloseBuild.mdx';

<OnCloseBuild />

- **Example:**

```ts
rsbuild.onCloseBuild(async () => {
  console.log('close build!');
});
```

## rsbuild.onBeforeStartDevServer

> Provides the same functionality as the [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) plugin hook.

import OnBeforeStartDevServer from '@en/shared/onBeforeStartDevServer.mdx';

<OnBeforeStartDevServer />

- **Example:**

```ts
rsbuild.onBeforeStartDevServer(({ server, environments }) => {
  console.log('before starting dev server.');
  console.log('the server is ', server);
  console.log('the environments contexts are: ', environments);
});
```

> See [Plugin hooks - onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) for more details.

## rsbuild.onAfterStartDevServer

> Provides the same functionality as the [onAfterStartDevServer](/plugins/dev/hooks#onafterstartdevserver) plugin hook.

import OnAfterStartDevServer from '@en/shared/onAfterStartDevServer.mdx';

<OnAfterStartDevServer />

- **Example:**

```ts
rsbuild.onAfterStartDevServer(({ port, routes }) => {
  console.log('this port is: ', port);
  console.log('this routes is: ', routes);
});
```

## rsbuild.onCloseDevServer

> Provides the same functionality as the [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) plugin hook.

import OnCloseDevServer from '@en/shared/onCloseDevServer.mdx';

<OnCloseDevServer />

- **Example:**

```ts
rsbuild.onCloseDevServer(async () => {
  console.log('close dev server!');
});
```

## rsbuild.onBeforeStartProdServer

> Provides the same functionality as the [onBeforeStartProdServer](/plugins/dev/hooks#onbeforestartprodserver) plugin hook.

import OnBeforeStartProdServer from '@en/shared/onBeforeStartProdServer.mdx';

<OnBeforeStartProdServer />

- **Example:**

```ts
rsbuild.onBeforeStartProdServer(() => {
  console.log('before start!');
});
```

## rsbuild.onAfterStartProdServer

> Provides the same functionality as the [onAfterStartProdServer](/plugins/dev/hooks#onafterstartprodserver) plugin hook.

import OnAfterStartProdServer from '@en/shared/onAfterStartProdServer.mdx';

<OnAfterStartProdServer />

- **Example:**

```ts
rsbuild.onAfterStartProdServer(({ port, routes }) => {
  console.log('this port is: ', port);
  console.log('this routes is: ', routes);
});
```

## rsbuild.onDevCompileDone

> Provides the same functionality as the [onDevCompileDone](/plugins/dev/hooks#ondevcompiledone) plugin hook.

import OnDevCompileDone from '@en/shared/onDevCompileDone.mdx';

<OnDevCompileDone />

- **Example:**

```ts
rsbuild.onDevCompileDone(({ isFirstCompile }) => {
  if (isFirstCompile) {
    console.log('first compile!');
  } else {
    console.log('re-compile!');
  }
});
```

## rsbuild.onExit

> Provides the same functionality as the [onExit](/plugins/dev/hooks#onexit) plugin hook.

import OnExit from '@en/shared/onExit.mdx';

<OnExit />

- **Example:**

```ts
rsbuild.onExit(({ exitCode }) => {
  console.log('exit: ', exitCode);
});
```

## rsbuild.getRsbuildConfig

> Provides the same functionality as the [getRsbuildConfig](/plugins/dev/core#apigetrsbuildconfig) plugin API.

import GetRsbuildConfig from '@en/shared/getRsbuildConfig.mdx';

<GetRsbuildConfig />

- **Example:**

```ts
rsbuild.onBeforeBuild(() => {
  const config = rsbuild.getRsbuildConfig();
  console.log(config.html?.title);
});
```

## rsbuild.getNormalizedConfig

> Provides the same functionality as the [getNormalizedConfig](/plugins/dev/core#apigetnormalizedconfig) plugin API.

import GetNormalizedConfig from '@en/shared/getNormalizedConfig.mdx';

<GetNormalizedConfig />

- **Example:**

```ts
rsbuild.onBeforeBuild(() => {
  const config = api.getNormalizedConfig();
  console.log(config.html.title);
});
```
